Set Classification API

This API allows the user to set the classification of a sample, either in the Spectra Intelligence cloud or locally.

POST /api/samples/{hash_value}/setclassification/{system}/

DELETE /api/samples/{hash_value}/setclassification/{system}/

Request Format

Request Parameters

NAME	REQUIRED	DESCRIPTION	TYPE
hash_value	Required	The sample hash for which the classification is being set or removed. If local, the sample must be present on the appliance. Supported hash types are SHA1, SHA256, SHA512, MD5.	path, string
system	Required	local or ticloud. The request must end with a trailing slash.	path, string
classification	Required for POST requests	Classification must be one of these values:goodware``suspicious``malicious	multipart/form-data, string
risk_score	Optional	If specified, it must be within range for the specified classification. If not specified, a default value is used:Goodware: 0Suspicious: 6Malicious: 10	multipart/form-data, string
threat_platform	Optional	If specified, it must be on the supported list (platforms and subplatforms). If not specified, the default value is Win32.	multipart/form-data, string
threat_type	Optional	If specified, it must be on the supported list (malware types). If not specified, the default value is Malware.	multipart/form-data, string
threat_name	Optional	If specified, must be an alphanumeric string not longer than 32 characters. If not specified, the default value is Generic.	multipart/form-data, string

Request Examples

cURL

# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/samples/cf8e42c4a0862c807f0de3c656d2cd1c99cc5a27/setclassification/local/' \
  --form classification=goodware \
  --form risk_score=0 \
  --header 'Authorization: Token exampletoken'

Python

import requests

# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the hostname in the URL
url = f"https://appliance.example.com/api/samples/{hash_value}/setclassification/local/"

payload = {
    "classification": "goodware",
    "risk_score": "0"
}

headers = {'Authorization': f'Token {token}'}

# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.post(url, headers=headers, data=payload)
print(response.text)

Response Format

Response Examples

{
  'classification': 'suspicious',
  'risk_score': 6,
  'threat_name': 'Win32.Malware.Generic'
}

Response Fields

Local POST

properties:
  classification:
    type: string
    enum:
      - goodware
      - suspicious
      - malicious
  risk_score:
    type: integer
    minimum: 0
    maximum: 10
  threat_name:
    type: string

Local DELETE

properties:
  code:
    type: integer
  detail:
    type: object
    properties:
      error:
        type: string
      message:
        type: string

Spectra Intelligence POST

Response body is available only in case of an error. If the return code is 200, no response body is included.

Response Status Codes

• 201

  POST success.

• 204

  DELETE success.

• 400

  Bad Request. Validation error. Parameters in the request are invalid or missing.

• 403

  Forbidden. Authentication credentials are invalid or missing.

• 404

  Local only:

  • POST and DELETE: sample does not exist on the appliance.
  • DELETE: sample has no current override to remove.

  Spectra Intelligence only:

  • Spectra Intelligence system is not configured.

• 429

  Too Many Requests. This happens if system resources are depleted. By default, this means that the system is using 90% or more of its available memory, or that it holds more than 50 items in the processing queue. The precise values are configurable (either on the Administration > Configuration > Resource Usage Limits page or via Spectra Detect Manager).